Skip to content

Conversation

@devin-ai-integration
Copy link
Contributor

@devin-ai-integration devin-ai-integration bot commented Nov 10, 2025

Add Vale check for missing punctuation between sentences

Summary

Added a new Vale style rule (SentencePunctuation.yml) to detect missing punctuation between sentences in documentation. The rule flags cases like "This is a sentence This is another sentence." where punctuation is missing after the first sentence.

The rule uses two heuristic patterns:

  1. Detects lowercase/digit/closer followed by space and common sentence starters (This, That, However, etc.)
  2. Detects lowercase/digit/closer followed by space, capitalized word, and auxiliary verbs (is, are, has, etc.)

Key implementation details:

  • Uses single-quoted YAML strings to avoid escaping issues
  • Uses [ \t]+ instead of \s+ to match only same-line gaps (prevents false positives in code blocks)
  • Removed ambiguous starters (The, A, An, In, On, At, To) to reduce false positives in YAML/code
  • Set to warning level and paragraph scope

Review & Testing Checklist for Human

  • Test on diverse documentation files: Run vale fern/products/docs/pages/**/*.mdx to check for unexpected false positives across the documentation corpus
  • Verify intended detections work: Create a test file with missing punctuation cases and confirm they're caught (e.g., "The SDK is great It provides many features.")
  • Check code block behavior: Verify the rule doesn't flag YAML comments or code samples inside <CodeBlock> components or fenced code blocks
  • Evaluate trade-offs: The rule won't catch cases like "sentence The next sentence" because "The" was removed from starters to reduce false positives. Confirm this trade-off is acceptable.
  • Consider severity level: The rule is set to warning. Decide if it should remain a warning or be promoted to error to block PRs with missing punctuation.

Test Plan

  1. Run Vale on a few existing documentation pages: vale fern/products/docs/pages/navigation/overview.mdx
  2. Create a test file with both good and bad examples:
    Good: "This is a sentence. This is another."
    Bad: "This is a sentence This is another."
    Bad: "The feature is useful It helps developers."
  3. Run vale test-file.mdx and verify it catches the bad examples without flagging the good ones
  4. Check that code blocks and YAML samples don't trigger false positives

Notes

@devin-ai-integration
Copy link
Contributor Author

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

@github-actions
Copy link
Contributor

…se positives

- Use single-quoted YAML strings to fix syntax errors
- Change \s+ to [ \t]+ to prevent cross-line matches
- Remove ambiguous starters (The, A, An, In, On, At, To) to reduce false positives in code blocks
- Tested on real documentation files to verify no false positives in code blocks

Co-Authored-By: Devin Logan <[email protected]>
@github-actions
Copy link
Contributor

@devalog devalog closed this Nov 12, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants